Inside Macintosh: QuickDraw GX Objects /

Chapter 7 - View-Related Objects / View-Related Objects Reference

View Device Functions / Measuring a Shape in Device Coordinates

GXGetShapeDeviceBounds

You can use the GXGetShapeDeviceBounds function to determine the bounding rectangle for the visible part of a shape on a view device.

boolean GXGetShapeDeviceBounds(gxShape source, gxViewPort port,
                              gxViewDevice device, 
                              gxRectangle *bounds);

source

A reference to the shape whose bounding rectangle you wish to test for inclusion on a device.

port

A reference to a view port to which the shape is drawn.

device

A reference to the view device that the shape displays on.

bounds

A pointer to a rectangle structure. On return the structure contains the bounding rectangle, in device coordinates, for the part of the shape that appears on the device.

function result

true if the bounding rectangle overlaps the view device clip; false if it does not.

DESCRIPTION

The GXGetShapeDeviceBounds function returns a value specifying whether the bounding rectangle of the shape drawn to the specified view port is within the clip area of the specified view device. The view port and view device must be in the same view group. The view port must be in the view port list of the shape's transform object.

You can specify nil for the port parameter, in which case GXGetShapeDeviceBounds includes all view ports in the view port list of
the source shape's transform. You can specify nil for the device parameter, in
which case GXGetShapeDeviceBounds includes any view device that intersects
any of the specified view ports.

Unless you pass nil for the bounds parameter, the function also returns in the bounds parameter the part of the shape's bounding rectangle that displays on the device. The rectangle shape is defined in device coordinates.

To determine a shape's bounding rectangle in geometry-space coordinates, use the GXGetShapeBounds function. To determine a shape's bounding rectangle in local coordinates, use the GXGetShapeLocalBounds function. To determine a shape's bounding rectangle in global coordinates, use the GXGetShapeGlobalBounds function.

SPECIAL CONSIDERATIONS

If the bounding rectangle of the source shape spans more than one device, this function posts an unable_to_get_bounds_on_multiple_devices warning.

ERRORS, WARNINGS, AND NOTICES

Errors
out_of_memory
shape_is_nil
invalid_viewPort_reference
invalid_viewDevice_reference
inconsistent_parameters	(debugging version)
Warnings
unable_to_get_bounds_on_multiple_devices

SEE ALSO

For an example of the use of this function, see page 7-59.

To calculate the area of a shape on a device, use the GXGetShapeDeviceArea function, described next.

The GXGetShapeBounds function is described in the geometric operations chapter of Inside Macintosh: QuickDraw GX Graphics. The GXGetShapeLocalBounds function is described on page 7-96. The GXGetShapeGlobalBounds function is described on page 7-125.

For information about coordinate spaces, see the section "About Drawing, Coordinate Conversion, and Clipping" beginning on page 7-30.